Content Editing Workflows

**Referenced Files in This Document** - [config.yml](file://src/admin/config.yml) - [index.html](file://src/admin/index.html) - [config.ts](file://tina/config.ts) - [package.json](file://package.json) - [README.md](file://README.md) - [2025-10-17-political-powerhouse.md](file://src/content/news/2025-10-17-political-powerhouse.md) - [adelaide-city-fc.md](file://src/content/cases/adelaide-city-fc.md) - [01-matt-neagle.md](file://src/content/team/01-matt-neagle.md) - [getting-started.md](file://src/content/knowledge/getting-started.md) - [site.json](file://src/_data/site.json) - [homepage.json](file://src/_data/homepage.json) - [.eleventy.js](file://.eleventy.js) - [curabitur-ullamcorper-ultricies-nisi.md](file://src/content/newsletters/curabitur-ullamcorper-ultricies-nisi.md) - [testimonials.json](file://src/_data/testimonials.json) - [clients.json](file://src/_data/clients.json) - [types.ts](file://tina/__generated__/types.ts)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document explains the content editing workflows in the Sveltia CMS-powered Sveltia CMS site. It covers how editors create, edit, preview, and publish content across all collection types, how the rich text editing interface works, how media is uploaded and optimized, and how drafts and publishing are managed. It also describes best practices for content organization, tagging, and metadata entry, along with examples of common editing scenarios and the relationship between CMS edits and static site regeneration.

Project Structure

The site is a static site generated by Eleventy with a Git-backed CMS. Content is authored in Markdown and JSON, organized into collections under src/content and src/_data. The CMS is exposed at /admin/ and integrates with GitHub for authentication and Git-backed persistence.

graph TB
subgraph "CMS Layer"
Admin["Admin UI<br/>/admin/index.html"]
Sveltia["Sveltia CMS runtime"]
end
subgraph "Content"
MD["Markdown content<br/>src/content/*"]
JSON["_data JSON<br/>src/_data/*"]
end
subgraph "Build"
Eleventy[".eleventy.js config"]
Site["_site output"]
end
Admin --> Sveltia
Sveltia --> MD
Sveltia --> JSON
MD --> Eleventy
JSON --> Eleventy
Eleventy --> Site

Diagram sources

  • [index.html:1-12](file://src/admin/index.html#L1-L12)
  • [config.yml:1-10](file://src/admin/config.yml#L1-L10)
  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)

Section sources

  • [README.md:1-669](file://README.md#L1-L669)
  • [package.json:1-32](file://package.json#L1-L32)

Core Components

  • Sveltia CMS admin UI: Accessible at /admin/, backed by GitHub OAuth, and configured via src/admin/config.yml.
  • TinaCMS schema: Defines editable collections and fields for local/Tina-based editing (reference only; not used in CI builds).
  • Eleventy build pipeline: Reads Markdown and JSON content, applies transforms, and produces the static site.
  • Media storage: Images and uploads are stored under src/assets/repository/images/uploads and referenced via relative URLs.

Key editing capabilities:

  • Rich text editing for body content in multiple collections.
  • Media selection with alt text management for images.
  • Draft flags and featured toggles to control visibility and prominence.
  • Metadata fields including title, date, author, excerpt, tags, and category.
  • Global data editing for site-wide settings and curated lists.

Section sources

  • [config.yml:1-774](file://src/admin/config.yml#L1-L774)
  • [config.ts:1-331](file://tina/config.ts#L1-L331)
  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [README.md:174-205](file://README.md#L174-L205)

Architecture Overview

The editing workflow is Git-backed. Editors sign in via Sveltia CMS, edit content in the admin UI, and save changes directly to the repository. A Cloudflare Worker serves the site and handles member portal authentication and APIs. The Eleventy build pipeline regenerates the static site after commits.

sequenceDiagram
participant Editor as "Editor"
participant Admin as "Sveltia Admin<br/>/admin/"
participant Repo as "GitHub Repo"
participant Worker as "Cloudflare Worker"
participant Build as "Eleventy Build"
participant Site as "Static Site"
Editor->>Admin : Sign in (GitHub OAuth)
Admin->>Repo : Save content changes (commit)
Repo-->>Build : Trigger build (CI/CD)
Build-->>Site : Generate _site/
Worker-->>Site : Serve static assets
Editor-->>Worker : Access /alliance/members/* (auth)

Diagram sources

  • [README.md:174-205](file://README.md#L174-L205)
  • [README.md:556-587](file://README.md#L556-L587)
  • [index.html:1-12](file://src/admin/index.html#L1-L12)

Detailed Component Analysis

Rich Text Editing Interface

  • Body fields across collections are rich text editors. Editors can format text, insert links, and apply structural markup appropriate for Markdown-based rendering.
  • Obsidian syntax support is applied during build, converting wikilinks and callouts to styled HTML.

Best practices:

  • Use semantic headings and concise paragraphs.
  • Prefer internal links using wikilink syntax for cross-references.
  • Use callouts sparingly to highlight important information.

Section sources

  • [config.yml:31-31](file://src/admin/config.yml#L31-L31)
  • [config.yml:58-58](file://src/admin/config.yml#L58-L58)
  • [config.yml:77-77](file://src/admin/config.yml#L77-L77)
  • [config.yml:105-105](file://src/admin/config.yml#L105-L105)
  • [.eleventy.js:217-239](file://.eleventy.js#L217-L239)
  • [getting-started.md:24-35](file://src/content/knowledge/getting-started.md#L24-L35)

Media Upload and Alt Text Management

  • Media folder: src/assets/repository/images/uploads
  • Public folder: /assets/repository/images/uploads
  • Editors can select images and enter alt text per image field. These are stored as relative URLs in front matter or JSON.

Optimization and best practices:

  • Use modern formats (e.g., WebP) when available.
  • Keep alt text descriptive and concise.
  • Ensure images are appropriately sized for the intended display.

Section sources

  • [config.yml:8-9](file://src/admin/config.yml#L8-L9)
  • [config.yml:25-26](file://src/admin/config.yml#L25-L26)
  • [config.yml:51-52](file://src/admin/config.yml#L51-L52)
  • [config.yml:70-71](file://src/admin/config.yml#L70-L71)
  • [config.yml:72-73](file://src/admin/config.yml#L72-L73)
  • [config.yml:198-199](file://src/admin/config.yml#L198-L199)
  • [config.yml:247-248](file://src/admin/config.yml#L247-L248)
  • [config.yml:369-369](file://src/admin/config.yml#L369-L369)
  • [config.yml:416-416](file://src/admin/config.yml#L416-L416)
  • [config.yml:493-493](file://src/admin/config.yml#L493-L493)
  • [config.yml:604-604](file://src/admin/config.yml#L604-L604)
  • [config.yml:611-612](file://src/admin/config.yml#L611-L612)
  • [config.yml:654-654](file://src/admin/config.yml#L654-L654)
  • [config.yml:707-708](file://src/admin/config.yml#L707-L708)
  • [config.yml:721-722](file://src/admin/config.yml#L721-L722)
  • [config.yml:735-736](file://src/admin/config.yml#L735-L736)

Preview and Publishing Workflow

  • Draft flag: Per-collection boolean to mark content as draft. Use this to keep content private until ready.
  • Featured flag: Promote content on listings and homepages.
  • Publishing: Saving in the CMS writes files directly to the repository, triggering a build and redeploy.

Common scenarios:

  • Create a draft news article, preview locally, then toggle draft to false and publish.
  • Use featured to highlight top stories or case studies.

Section sources

  • [config.yml:30-30](file://src/admin/config.yml#L30-L30)
  • [config.yml:57-57](file://src/admin/config.yml#L57-L57)
  • [config.yml:76-76](file://src/admin/config.yml#L76-L76)
  • [config.yml:104-104](file://src/admin/config.yml#L104-L104)
  • [config.yml:197-197](file://src/admin/config.yml#L197-L197)
  • [config.yml:242-242](file://src/admin/config.yml#L242-L242)
  • [config.yml:264-264](file://src/admin/config.yml#L264-L264)
  • [config.yml:296-296](file://src/admin/config.yml#L296-L296)
  • [config.yml:311-311](file://src/admin/config.yml#L311-L311)
  • [config.yml:333-333](file://src/admin/config.yml#L333-L333)
  • [config.yml:354-354](file://src/admin/config.yml#L354-L354)
  • [config.yml:380-380](file://src/admin/config.yml#L380-L380)
  • [config.yml:405-405](file://src/admin/config.yml#L405-L405)
  • [config.yml:444-444](file://src/admin/config.yml#L444-L444)
  • [config.yml:487-487](file://src/admin/config.yml#L487-L487)
  • [config.yml:544-544](file://src/admin/config.yml#L544-L544)
  • [config.yml:616-616](file://src/admin/config.yml#L616-L616)
  • [config.yml:662-662](file://src/admin/config.yml#L662-L662)
  • [config.yml:708-708](file://src/admin/config.yml#L708-L708)
  • [config.yml:722-722](file://src/admin/config.yml#L722-L722)
  • [config.yml:736-736](file://src/admin/config.yml#L736-L736)

Content Organization, Tagging, and Metadata Entry

  • News & Insights: title, date, author, excerpt, image, image_alt, pdf_url/pdf_label, featured, draft, body.
  • Case Studies: client, category (select), engagement title, image, image_alt, quote, quote_author, order, featured, draft, body.
  • Team Members: anchor, name, role, order, index/profile images and alt texts, short bio, featured, draft, full bio.
  • Knowledge Base: title, date, author, excerpt, tags_list (flat list), body.
  • Newsletters: title, date, excerpt, pdf_link, archive_link, featured, draft.

Best practices:

  • Always include required fields as indicated by the schema.
  • Use tags_list for Knowledge Base articles to enable client-side filtering.
  • Keep excerpts concise and informative.
  • Use categories consistently across collections.

Section sources

  • [config.yml:15-32](file://src/admin/config.yml#L15-L32)
  • [config.yml:33-58](file://src/admin/config.yml#L33-L58)
  • [config.yml:60-78](file://src/admin/config.yml#L60-L78)
  • [config.yml:79-91](file://src/admin/config.yml#L79-L91)
  • [config.yml:92-105](file://src/admin/config.yml#L92-L105)
  • [2025-10-17-political-powerhouse.md:1-18](file://src/content/news/2025-10-17-political-powerhouse.md#L1-L18)
  • [adelaide-city-fc.md:1-14](file://src/content/cases/adelaide-city-fc.md#L1-L14)
  • [01-matt-neagle.md:1-21](file://src/content/team/01-matt-neagle.md#L1-L21)
  • [getting-started.md:37-51](file://src/content/knowledge/getting-started.md#L37-L51)

Common Editing Scenarios and Patterns

  • Creating a news article:
    • Open News & Insights collection in the CMS.
    • Fill in title, date, author, excerpt, image, image_alt, and body.
    • Toggle draft to false when ready to publish.
  • Adding a case study:
    • Choose category from the select dropdown.
    • Enter client, engagement title, image, quote, and body.
    • Use order to control display sequence.
  • Updating site-wide settings:
    • Use Site Settings to update contact info, social links, and other global metadata.
  • Managing curated lists:
    • Use Testimonials, Client Logos, IAA Partners, and other list-based collections to manage carousel and directory content.

Section sources

  • [config.yml:108-130](file://src/admin/config.yml#L108-L130)
  • [config.yml:131-158](file://src/admin/config.yml#L131-L158)
  • [config.yml:159-220](file://src/admin/config.yml#L159-L220)
  • [config.yml:221-262](file://src/admin/config.yml#L221-L262)
  • [config.yml:264-336](file://src/admin/config.yml#L264-L336)
  • [config.yml:337-406](file://src/admin/config.yml#L337-L406)
  • [config.yml:407-664](file://src/admin/config.yml#L407-L664)
  • [config.yml:665-774](file://src/admin/config.yml#L665-L774)
  • [site.json:1-20](file://src/_data/site.json#L1-L20)
  • [homepage.json:1-23](file://src/_data/homepage.json#L1-L23)
  • [testimonials.json:1-24](file://src/_data/testimonials.json#L1-L24)
  • [clients.json:1-104](file://src/_data/clients.json#L1-L104)

Collaborative Editing and Review

  • Authentication: Sveltia CMS uses GitHub OAuth via a hosted proxy. Editors sign in with GitHub and are granted access based on repository permissions.
  • Review: Because edits commit directly to the repository, all changes are visible in the commit history. Teams can use pull requests or repository review settings to approve changes before merging.

Section sources

  • [README.md:185-187](file://README.md#L185-L187)
  • [README.md:188-188](file://README.md#L188-L188)

Relationship Between CMS Edits and Static Site Regeneration

  • The CMS writes content directly to the repository.
  • Cloudflare Workers trigger a build on pushes to main, generating the static site and serving it at runtime.
  • The admin UI itself is included in the build output under _site/admin/.
flowchart TD
Start(["Editor saves in CMS"]) --> Commit["Commit to repository"]
Commit --> Build["Eleventy build pipeline"]
Build --> Output["_site generation"]
Output --> Deploy["Deploy via Cloudflare Worker"]
Deploy --> Serve["Serve static site"]

Diagram sources

  • [README.md:556-587](file://README.md#L556-L587)
  • [package.json:5-12](file://package.json#L5-L12)

Section sources

  • [README.md:174-205](file://README.md#L174-L205)
  • [README.md:556-587](file://README.md#L556-L587)
  • [package.json:5-12](file://package.json#L5-L12)

Dependency Analysis

  • CMS configuration:
    • src/admin/config.yml defines all editable collections and fields for Sveltia CMS.
    • tina/config.ts defines the same schema for local/Tina-based environments (reference only).
  • Build pipeline:
    • .eleventy.js configures passthrough copying, filters, collections, and transforms (including Obsidian syntax).
  • Media:
    • Sharp is included for potential image optimization tasks in the build environment.
graph LR
ConfigYAML["src/admin/config.yml"] --> CMS["Sveltia CMS"]
ConfigTS["tina/config.ts"] --> Tina["TinaCMS (local)"]
CMS --> Repo["Repository"]
Tina --> Repo
Repo --> Eleventy[".eleventy.js"]
Eleventy --> Site["_site"]
Sharp["sharp (dependency)"] --> Eleventy

Diagram sources

  • [config.yml:1-10](file://src/admin/config.yml#L1-L10)
  • [config.ts:1-331](file://tina/config.ts#L1-L331)
  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [package.json:19-19](file://package.json#L19-L19)

Section sources

  • [config.yml:1-774](file://src/admin/config.yml#L1-L774)
  • [config.ts:1-331](file://tina/config.ts#L1-L331)
  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [package.json:19-19](file://package.json#L19-L19)

Performance Considerations

  • Keep media files appropriately sized and in modern formats to reduce load times.
  • Use excerpts and summaries to improve listing performance.
  • Leverage Eleventy’s filters and transforms judiciously to avoid heavy computations on every build.

Troubleshooting Guide

  • CMS not loading:
    • Verify the admin entry point exists and the CMS script is loaded.
  • Media upload issues:
    • Confirm media folder and public folder paths in the CMS config.
  • Rich text formatting not rendering:
    • Ensure the body field is configured as rich text and that Obsidian syntax is supported.
  • Draft content still visible:
    • Check the draft flag and collection-specific visibility logic.
  • Build failures:
    • Review Eleventy configuration and transforms for errors.

Section sources

  • [index.html:1-12](file://src/admin/index.html#L1-L12)
  • [config.yml:8-9](file://src/admin/config.yml#L8-L9)
  • [config.yml:31-31](file://src/admin/config.yml#L31-L31)
  • [config.yml:58-58](file://src/admin/config.yml#L58-L58)
  • [config.yml:77-77](file://src/admin/config.yml#L77-L77)
  • [config.yml:105-105](file://src/admin/config.yml#L105-L105)
  • [.eleventy.js:217-239](file://.eleventy.js#L217-L239)

Conclusion

The Sveltia CMS workflow provides a straightforward, Git-backed editing experience with rich text editing, media management, and robust publishing. By following the field definitions, best practices for metadata and tagging, and the preview-publish cycle, editors can efficiently manage content across all collections while ensuring reliable static site regeneration.

Appendices

  • Obsidian Knowledge Base publishing workflow:
    • Notes are written in Obsidian, committed to the repository, and published automatically upon build.
  • Member portal authentication:
    • Magic link email authentication handled by the Cloudflare Worker; not part of the CMS but affects access to member-only content.

Section sources

  • [README.md:411-417](file://README.md#L411-L417)
  • [README.md:425-477](file://README.md#L425-L477)